home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.004 / xemacs-1 / xemacs-19.13 / src / events.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-08-30  |  14.1 KB  |  431 lines
  1. /* Definitions for the new event model;
  2.    created 16-jul-91 by Jamie Zawinski
  3.    Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
  4.  
  5. This file is part of XEmacs.
  6.  
  7. XEmacs is free software; you can redistribute it and/or modify it
  8. under the terms of the GNU General Public License as published by the
  9. Free Software Foundation; either version 2, or (at your option) any
  10. later version.
  11.  
  12. XEmacs is distributed in the hope that it will be useful, but WITHOUT
  13. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14. FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15. for more details.
  16.  
  17. You should have received a copy of the GNU General Public License
  18. along with XEmacs; see the file COPYING.  If not, write to the Free
  19. Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
  20.  
  21. /* Synched up with: Not in FSF. */
  22.  
  23. #ifndef _XEMACS_EVENTS_H_
  24. #define _XEMACS_EVENTS_H_
  25.  
  26. #include "systime.h"
  27.  
  28. /* There is one object, called an event_stream.  This object contains 
  29.    callback functions for doing the window-system dependent operations that
  30.    emacs requires.
  31.  
  32.    If emacs is compiled with support for X11 and the X Toolkit, then this
  33.    event_stream structure will contain functions that can cope with input
  34.    on emacs windows on multiple displays, as well as input from dumb tty
  35.    frames.  
  36.  
  37.    If it is desired to have emacs able to open frames on the displays of
  38.    multiple heterogeneous machines, X11 and SunView, or X11 and NeXT, for
  39.    example, then it will be necessary to construct an event_stream structure
  40.    that can cope with the given types.  Currently, the only implemented
  41.    event_streams are for dumb-ttys, and for X11 plus dumb-ttys.
  42.    
  43.    To implement this for one window system is relatively clean and simple.  
  44.    To implement this for multiple window systems is hard and hairy, so we 
  45.    are punting for now.
  46.  
  47.   The slots of the event_stream structure:
  48.  
  49.  next_event_cb        A function which fills in an emacs_event struture
  50.             with the next event available.  If there is no event
  51.             available, then this should block.
  52.  
  53.             IMPORTANT: timer events and especially process
  54.             events *must not* be returned if there are
  55.             events of other types available; otherwise you
  56.             can end up with an infinite loop in Fdiscard_input().
  57.  
  58.  event_pending_cb    A function which says whether there are events to be
  59.             read.  If called with an argument of 0, then this
  60.             should say whether calling the next_event_cb will
  61.             block.  If called with an argument of 1, then this
  62.             should say whether there are user-generated events
  63.             pending (that is, keypresses or mouse-clicks).  This
  64.             is used for redisplay optimization, among other 
  65.             things.  On dumb ttys, these two results are the 
  66.             same, but under a window system, they are not.
  67.  
  68.             If this function is not sure whether there are events
  69.             to be read, it *must* return 0.  Otherwise various
  70.             undesirable effects will occur, such as redisplay
  71.             not occurring until the next event occurs.
  72.  
  73.  handle_magic_event_cb    Emacs calls this with an event structure which
  74.               contains window-system dependent information that
  75.             emacs doesn't need to know about, but which must
  76.             happen in order.  If the next_event_cb never returns
  77.             an event of type "magic", this will never be used.
  78.  
  79.  add_timeout_cb        Called with an EMACS_TIME, the absolute time at
  80.             which a wakeup event should be generated; and a
  81.             void *, which is an arbitrary value that will be
  82.             returned in the timeout event.  The timeouts
  83.             generated by this function should be one-shots:
  84.             they fire once and then disappear.  This callback
  85.             should return an int id-number which uniquely
  86.             identifies this wakeup.  If an implementation
  87.             doesn't have microseconds or millisecond
  88.             granularity, it should round up to the closest
  89.             value it can deal with.
  90.  
  91.  remove_timeout_cb    Called with an int, the id number of a wakeup to 
  92.              discard.  This id number must have been returned by
  93.             the add_timeout_cb.  If the given wakeup has
  94.             already expired, this should do nothing.
  95.  
  96.  select_process_cb    These callbacks tell the underlying implementation to
  97.  unselect_process_cb    add or remove a file descriptor from the list of fds
  98.               which are polled for inferior-process input.  When
  99.             input becomes available on the given process
  100.             connection, an event of type "process" should be
  101.             generated.
  102.  
  103.  select_device_cb    These callbacks tell the underlying implementation 
  104.  unselect_device_cb    to add or remove a device from the list of devices
  105.                         which are polled for user-input.
  106.  
  107.  quitp_cb        A handler function called from the `QUIT' macro which
  108.             should check whether the quit character has been
  109.             typed.  On systems with SIGIO, this will not be called
  110.             unless the `sigio_happened' flag is true (it is set
  111.             from the SIGIO handler).
  112.  
  113.  Emacs has its own event structures, which are distinct from the event
  114.  structures used by X or any other window system.  It is the job of the
  115.  event_stream layer to translate to this format.
  116.  
  117.  NOTE: All timestamps are measured as milliseconds since Emacs started.
  118.  
  119.  key_press_event    
  120.     event_channel    A token representing which keyboard generated it.
  121.             For this kind of event, this is a frame object.
  122.     timestamp        When it happened
  123.     key            What keysym this is; an integer or a symbol.
  124.             If this is an integer, it will be in the printing
  125.             ASCII range: >32 and <127.
  126.     modifiers        Bucky-bits on that key: control, meta, etc.
  127.             For most keys, Shift is not a bit; that is implicit
  128.             in the keyboard layout.
  129.  
  130.  button_press_event
  131.  button_release_event
  132.     event_channel    A token representing which mouse generated it.
  133.             For this kind of event, this is a frame object.
  134.     timestamp        When it happened
  135.     button        What button went down or up.
  136.     modifiers        Bucky-bits on that button: shift, control, meta, etc.
  137.     x, y        Where it was at the button-state-change (in pixels).
  138.  
  139.  pointer_motion_event
  140.     event_channel    A token representing which mouse generated it.
  141.             For this kind of event, this is a frame object.
  142.     timestamp        When it happened
  143.     x, y        Where it was after it moved (in pixels).
  144.     modifiers        Bucky-bits down when the motion was detected.
  145.             (Possibly not all window systems will provide this?)
  146.  
  147.  process_event
  148.     timestamp        When it happened
  149.     process        the emacs "process" object in question
  150.  
  151.  timeout_event
  152.     timestamp        Now (really, when the timeout was signalled)
  153.     interval_id        The ID returned when the associated call to
  154.             add_timeout_cb() was made
  155.     ------ the rest of the fields are filled in by Emacs -----
  156.     id_number        The Emacs timeout ID for this timeout (more
  157.             than one timeout event can have the same value
  158.             here, since Emacs timeouts, as opposed to
  159.             add_timeout_cb() timeouts, can resignal
  160.             themselves)
  161.     function        An elisp function to call when this timeout is
  162.             processed.
  163.     object        The object passed to that function.
  164.  
  165.  eval_event
  166.     timestamp        When it happened
  167.     function        An elisp function to call with this event object.
  168.     object        Anything.
  169.             This kind of event is used internally; sometimes the
  170.             window system interface would like to inform emacs of
  171.             some user action (such as focusing on another frame)
  172.             but needs that to happen synchronously with the other
  173.             user input, like keypresses.  This is useful when
  174.             events are reported through callbacks rather
  175.             than in the standard event stream.
  176.  
  177.  misc_user_event
  178.     timestamp        When it happened
  179.     function        An elisp function to call with this event object.
  180.     object        Anything.
  181.             This is similar to an eval_event, except that it is
  182.             generated by user actions: selections in the
  183.             menubar or scrollbar actions.  It is a "command"
  184.             event, like key and mouse presses (and unlike mouse
  185.             motion, process output, and enter and leave window
  186.             hooks).  In many ways, eval_events are not the same
  187.             as keypresses or misc_user_events.
  188.  
  189.  magic_event
  190.             No user-serviceable parts within.  This is for things
  191.             like KeymapNotify and ExposeRegion events and so on
  192.             that emacs itself doesn't care about, but which it
  193.             must do something with for proper interaction with
  194.             the window system.
  195.  
  196.             Magic_events are handled somewhat asynchronously, just
  197.             like subprocess filters.  However, occasionally a 
  198.             magic_event needs to be handled synchronously; in that
  199.             case, the asynchronous handling of the magic_event will
  200.             push an eval_event back onto the queue, which will be 
  201.             handled synchronously later.  This is one of the
  202.             reasons why eval_events exist; I'm not entirely happy
  203.             with this aspect of this event model.
  204.  */
  205.  
  206.  
  207. struct Lisp_Event;
  208. struct Lisp_Process;
  209.  
  210. struct event_stream
  211. {
  212.   int  (*event_pending_p)    (int);
  213.   void (*next_event_cb)        (struct Lisp_Event *);
  214.   void (*handle_magic_event_cb)    (struct Lisp_Event *);
  215.   int  (*add_timeout_cb)    (EMACS_TIME);
  216.   void (*remove_timeout_cb)    (int);
  217.   void (*select_device_cb)    (struct device *);
  218.   void (*unselect_device_cb)    (struct device *);
  219.   void (*select_process_cb)    (struct Lisp_Process *);
  220.   void (*unselect_process_cb)    (struct Lisp_Process *);
  221.   void (*quit_p_cb)        (void);
  222. };
  223.  
  224.  
  225. extern struct event_stream *event_stream;
  226.  
  227. typedef enum emacs_event_type
  228. {
  229.   empty_event,
  230.   key_press_event,
  231.   button_press_event,
  232.   button_release_event,
  233.   pointer_motion_event,
  234.   process_event,
  235.   timeout_event,
  236.   magic_event,
  237.   eval_event,
  238.   misc_user_event,
  239.   dead_event
  240. } emacs_event_type;
  241.  
  242. #define first_event_type empty_event
  243. #define last_event_type dead_event
  244.  
  245.  
  246. struct key_data
  247. {
  248.   Lisp_Object       keysym;
  249.   unsigned char     modifiers;
  250. };
  251.  
  252. struct button_data
  253. {
  254.   int               button;
  255.   unsigned char     modifiers;
  256.   int               x, y;
  257. };
  258.  
  259. struct motion_data
  260. {
  261.   int               x, y;
  262.   unsigned char     modifiers;
  263. };
  264.  
  265. struct process_data
  266. {
  267.   Lisp_Object       process;
  268. };
  269.  
  270. struct timeout_data
  271. {
  272.   int            interval_id;
  273.   int            id_number;
  274.   Lisp_Object        function, object;
  275. };
  276.  
  277. struct eval_data
  278. {
  279.   Lisp_Object       function;
  280.   Lisp_Object        object;
  281. };
  282.  
  283. #if defined (HAVE_X_WINDOWS) && defined(emacs)
  284. # include <X11/Xlib.h>
  285. #endif
  286.  
  287. #if defined (HAVE_NEXTSTEP) && defined(emacs)
  288. # import <appkit/appkit.h>
  289. #endif
  290.  
  291. union magic_data
  292. {
  293.   char             underlying_tty_event;
  294. #ifdef HAVE_X_WINDOWS
  295.   XEvent           underlying_x_event;
  296. #endif
  297. #ifdef HAVE_NEXTSTEP
  298.   NXEvent          underlying_ns_event;
  299. #endif
  300. };
  301.  
  302. struct Lisp_Event
  303. {
  304.   /* header->next (aka event_next ()) is used as follows:
  305.      - For dead events, this is the next dead one.
  306.      - For events on the command_event_queue, the next one on the queue.
  307.      - Otherwise it's 0.
  308.    */
  309.   struct lrecord_header lheader;
  310.   struct Lisp_Event    *next;
  311.   emacs_event_type    event_type;
  312.   Lisp_Object        channel;
  313.   Lisp_Object        device;
  314.   unsigned int        timestamp;
  315.   union
  316.     {
  317.       struct key_data     key;
  318.       struct button_data  button;
  319.       struct motion_data  motion;
  320.       struct process_data process;
  321.       struct timeout_data timeout;
  322.       struct eval_data    eval;        /* misc_user_event uses this too */
  323.       union magic_data    magic;
  324.     } event;
  325. };
  326.  
  327. DECLARE_LRECORD (event, struct Lisp_Event);
  328. #define XEVENT(x) XRECORD (x, event, struct Lisp_Event)
  329. #define XSETEVENT(x, p) XSETRECORD (x, p, event)
  330. #define EVENTP(x) RECORDP (x, event)
  331. #define CHECK_EVENT(x, i) CHECK_RECORD (x, event)
  332.  
  333. #define EVENT_DEVICE(a) ((a)->device)
  334. #define EVENT_TYPE(a) ((a)->event_type)
  335. #define event_next(a) ((a)->next)
  336. #define set_event_next(a, n) do { ((a)->next = (n)); } while (0)
  337.  
  338. #define EVENT_LIVE_P(a) (EVENT_TYPE (a) != dead_event)
  339.  
  340. #define CHECK_LIVE_EVENT(x, i)                        \
  341.   do { CHECK_EVENT (x, i);                        \
  342.        if (! EVENTP (x)                            \
  343.        || ! EVENT_LIVE_P (XEVENT (x)))                \
  344.          x = wrong_type_argument (Qevent_live_p, (x)); } while (0)
  345.  
  346.  
  347. extern Lisp_Object Qevent_live_p;
  348.  
  349. /* The modifiers emacs knows about; these appear in key and button events.
  350.  */
  351. #define MOD_CONTROL    (1<<0)
  352. #define MOD_META    (1<<1)
  353. #define MOD_SUPER    (1<<2)
  354. #define MOD_HYPER    (1<<3)
  355. #define MOD_ALT        (1<<4)
  356. #define MOD_SHIFT    (1<<5)  /* not used for dual-case characters */
  357.  
  358. /* Note: under X Windows, MOD_ALT is generated by the Alt key if there are
  359.    both Alt and Meta keys.  If there are no Meta keys, then Alt generates
  360.    MOD_META instead.
  361.  */
  362.  
  363. #ifdef emacs
  364. /* Maybe this should be trickier */
  365. #define KEYSYM(x) (intern (x))
  366.  
  367. extern void format_event_object (char *buf, struct Lisp_Event *e, int brief);
  368. extern void character_to_event (Emchar c, struct Lisp_Event *event,
  369.                 struct device *d);
  370.  
  371.  
  372. /* True is this is a non-internal event
  373.    (keyboard press, menu, scrollbar, mouse button) */
  374. extern int command_event_p (struct Lisp_Event *event);
  375.  
  376. extern int event_stream_event_pending_p (int user);
  377. extern void event_stream_next_event (struct Lisp_Event *event);
  378. extern void event_stream_handle_magic_event (struct Lisp_Event *event);
  379. extern void event_stream_select_device (struct device *d);
  380. extern void event_stream_unselect_device (struct device *d);
  381. extern void event_stream_select_process (struct Lisp_Process *proc);
  382. extern void event_stream_unselect_process (struct Lisp_Process *proc);
  383. extern void event_stream_quit_p (void);
  384.  
  385. struct low_level_timeout
  386. {
  387.   int id;
  388.   EMACS_TIME time;
  389.   struct low_level_timeout *next;
  390. };
  391.  
  392. extern int add_low_level_timeout (struct low_level_timeout **timeout_list,
  393.                   EMACS_TIME time);
  394. extern void remove_low_level_timeout (struct low_level_timeout **timeout_list,
  395.                       int id);
  396. extern int get_low_level_timeout_interval (struct low_level_timeout *
  397.                        timeout_list, EMACS_TIME *interval);
  398. extern int pop_low_level_timeout (struct low_level_timeout **timeout_list,
  399.                   EMACS_TIME *time_out);
  400.  
  401. extern int event_stream_generate_wakeup (unsigned int milliseconds,
  402.                      unsigned int vanilliseconds,
  403.                      Lisp_Object function,
  404.                      Lisp_Object object,
  405.                      int async_p);
  406. extern void event_stream_deal_with_async_timeout (int interval_id);
  407.  
  408. /* from signal.c */
  409. extern int event_stream_add_async_timeout (EMACS_TIME time);
  410. extern void event_stream_remove_async_timeout (int id);
  411.  
  412. /* Ceci n'est pas un pipe. */
  413. extern int signal_event_pipe[];
  414.  
  415. extern void signal_fake_event (void);
  416. extern void drain_signal_event_pipe (void);
  417.  
  418. extern int emacs_is_blocking;
  419.  
  420. extern Lisp_Object Vcontrolling_terminal;
  421.  
  422. extern volatile int sigint_happened;
  423.  
  424. /* Define this if you want the tty event stream to be used when the
  425.    first device is tty, even if HAVE_X_WINDOWS is defined */
  426. /* #define DEBUG_TTY_EVENT_STREAM */
  427.  
  428. #endif /* emacs */
  429.  
  430. #endif /* _XEMACS_EVENTS_H_ */
  431.